Summary

Index updates now skip bucket, tree, and timestamp writes when the indexed value is unchanged. The combined change also caches compiled index evaluators, avoids object-normalization work for primitive values, repairs a BasicIndex bookkeeping edge case, and adds model-based property coverage for both index types.

Root cause

Every update previously called the public remove/add paths for every index, even when the indexed value stayed in the same normalized bucket. That repeated expression compilation, normalization, map/set or B+ tree writes, and timestamp updates for changes to unrelated row fields.

The first no-op guard also exposed an existing partial-state case in BasicIndex: if removal expression evaluation failed, the value bucket could retain the key while indexedKeys dropped it. Checking only bucket membership could then return early without repairing keyCount.

Approach

• Evaluate and normalize the old and new indexed values once.
• Compare normalized values with SameValueZero semantics, matching JavaScript Map keys for values such as NaN and signed zero.
• Return early only when the value is unchanged and the expected bucket contains the key. BasicIndex also confirms membership in indexedKeys.
• Move changed values through private bucket helpers, avoiding duplicate evaluation and updating the timestamp once.
• Preserve the existing public remove/add fallback when expression evaluation fails.
• Compile each index expression once and reuse its evaluator.
• Return primitive values from normalizeValue() before object-specific checks.
• Check randomized valid mutation sequences against a reference model after every operation.

Key invariants

• A no-op update leaves buckets, ordered entries, key counts, and timestamps unchanged.
• A real move removes the key from the old bucket and adds it to the new bucket exactly once.
• SameValueZero governs bucket identity; custom ordering comparators do not redefine equality.
• undefined, null, NaN, signed zero, dates, byte arrays, object identity, and custom comparators retain their prior lookup semantics.
• keyCount, indexed keys, exact buckets, ordered entries, equality lookups, range queries, and rebuilt state agree with the reference model.
• Expression-evaluation failures retain the prior fallback behavior.

Non-goals

• This does not change how stale caller-supplied oldItem values are handled. fix(db): a key in BasicIndex/BTreeIndex lives in at most one bucket #1517 owns the one-key/one-bucket invariant and its extra reverse-map memory cost.
• This does not take the full perf: systematic live query engine optimizations (31 profile-guided iterations) #1645 change set. It absorbs only evaluator caching and primitive normalization, allowing the remaining useful parts to be cherry-picked separately.
• This does not change public APIs or timestamp semantics.

Trade-offs

The no-op path performs cheap membership checks before returning. This is slightly more work than comparing values alone, but prevents an optimization from hiding inconsistent bookkeeping.

A reverse key-to-bucket map would also solve stale oldItem values, but adds one map entry per indexed row per index and broadens this performance change into a separate correctness invariant. That work remains isolated in #1517.

Benchmark

The original #1691 microbenchmark used 10,000 unique indexed rows, four indexes, 5,000 updates, and five runs; medians are shown:

This is a focused index microbenchmark, not an end-to-end application result. The gain depends on index count, bucket shape, and how often indexed values change. Evaluator caching and the primitive normalization fast path were added after this measurement.

Verification

pnpm exec vitest run packages/db/tests/index-update.property.test.ts packages/db/tests/index-update-short-circuit.test.ts
pnpm --filter @tanstack/db test
pnpm --filter @tanstack/db build
pnpm exec eslint packages/db/src/indexes/base-index.ts packages/db/src/indexes/basic-index.ts packages/db/src/indexes/btree-index.ts packages/db/src/utils/comparison.ts packages/db/tests/index-update-short-circuit.test.ts packages/db/tests/index-update.property.test.ts
pnpm exec prettier --check .changeset/quick-trees-rest.md packages/db/src/indexes/base-index.ts packages/db/src/indexes/basic-index.ts packages/db/src/indexes/btree-index.ts packages/db/src/utils/comparison.ts packages/db/tests/index-update-short-circuit.test.ts packages/db/tests/index-update.property.test.ts

• Focused update and property suite: 23 tests passed.
• Full @tanstack/db suite: 2,483 tests passed, 5 skipped.
• Package build, ESLint, and Prettier checks passed.

Files changed

• base-index.ts: cache the compiled expression evaluator.
• basic-index.ts: short-circuit unchanged updates, use direct bucket moves, and guard key bookkeeping.
• btree-index.ts: short-circuit unchanged updates and use direct bucket moves.
• comparison.ts: add SameValueZero equality and a primitive normalization fast path.
• index-update-short-circuit.test.ts: cover no-op updates, real moves, edge values, comparators, and evaluation failures.
• index-update.property.test.ts: compare randomized mutation sequences with a reference model.
• quick-trees-rest.md: provide one combined patch changeset.

Related: #1517, #1645

Summary by CodeRabbit

• Bug Fixes
  • Avoid unnecessary bucket writes on no-op updates; preserves timestamps and reuses bucket instances.
  • Improve indexed value comparison with SameValueZero semantics (e.g., NaN), while keeping undefined and null distinct.
  • Incrementally move keys between index buckets on changes, with consistent state even when index value evaluation fails.
• Tests
  • Added cross-index update short-circuit tests and expanded failure/edge-case coverage.
  • Added property-based randomized put/delete invariants tests for update correctness.
• Chores
  • Cache compiled index expression evaluation to speed up repeated updates.